% Extern.tex copyright 1992 Victor Eijkhout
%
\Chapter[chap:referencing]
Referencing

In manuals and scientific documents you often want to write something
like `see Chapter~4'. But what if you shuffle the chapters a bit? It
would be nice if the number would be updated automatically. With
\Lollipop, as with many other \TeX\ macro packages, this is easily
done.

Here is an example to set the mood for the rest of this chapter.
The sort of thing that is referred to most is a heading. So suppose
you want to refer to a section number.

\Example
\DefineHeading:TestSection
 line:start Style:italic TestSectionCounter Spaces:2 title
 line:stop Stop
\TestSection[one:section?] First section\par
After this section will come section~\ref[other:section!].

\TestSection[other:section!] Another section\par
This is the section that came after section~\ref[one:section?].
\ExampleStop

\Section What and how do you reference?

You can reference not only headings but everything that has a
counter. Thus all generic constructs can be referenced, and in
addition you can reference item numbers in a list (there are examples
of this latter possibility in section~\ref[sec:bib]). The simplest way
of referencing something is to put the key in square brackets behind
it:

\Ver>\Section[this:section] The title of This Section<Rev
The key is used by typing
\Ver>\ref[this:section]<Rev

As you may have guessed from the above examples, keys can contain all
sorts of characters. Only brackets, braces, and the hash sign are
excepted. You get an error message if you try to use the same key
twice.

Another way of declaring a key is to use the command \refcs{label}
carrying the key
\Ver>\label[the:key]<Rev
This can be useful if you want to declare two keys for a single
reference. Make sure that the \cs{label} command is not part of the
title. Unexplained phenomena occur if you do that. Instead put the
label after the construct you want to reference:
\Ver>\Section Precautions and remedies

\label[sec:precautions]\label[sec:remedies]
In this section ...<Rev

\Section[sec:shape:reference] The shape of the reference

By default, a reference consists of just the number of the thing you
reference. You can customize the way an object is referenced by using
the option \refopt{label} in its definition. For instance, often you
want things like parentheses around references. Putting this
information in the label definition saves you a lot of work in case
you change your mind later.

\Example
\DefineHeading:TestSection
 line:start Style:italic TestSectionCounter Spaces:2 title line:stop
 label:start ( TestSectionCounter ) label:stop Stop
\TestSection[one:section?2] First section\par
After this section will come section~\ref[other:section!2].

\TestSection[other:section!2] Another section\par
This is the section that came after section~\ref[one:section?2].
\ExampleStop

Another use of customized labels is including other counters in the
reference:
 
\Example
\DefineHeading:TestChapter 
 line:start Style:bold TestChapterCounter / title line:stop Stop
\DefineHeading:TestSection
 line:start Style:italic TestSectionCounter Spaces:2 title line:stop
 label:start TestChapterCounter . 
             TestSectionCounter label:stop Stop
\TestChapter First chapter\par
Pretty short chapter
\TestChapter Second chapter\par
\TestSection[one:section?3] First section\par
After this section will come section~\ref[other:section!3].

\TestSection[other:section!3] Another section\par
This is the section that came after section~\ref[one:section?3].
\ExampleStop

A more surprising application of explicit definition of labels is
inclusion of the title in the reference.
\Example
\DefineHeading:TestSection
 line:start Style:italic TestSectionCounter Spaces:2 title line:stop 
 label:start TestSectionCounter literal: Spaces:1 
             Style:italic title label:stop Stop
\TestSection[one:section?4] First section\par
After this section will come section~\ref[other:section!4].

\TestSection[other:section!4] Another section\par
This is the section that came after section~\ref[one:section?4].
\ExampleStop

\Section[sec:ref-local] Local references

Some documents are
collated out of parts that were documents in themselves. 
The \Lollipop\ command \cs{InputFile} facilitates in a number
of ways working with such a segmented file (see
section~\ref[sec:InputFile]). One of the problems with input files is
that in such a case it may happen that the same reference key is used
in more than one part of the document. This phenomenon is
not at all unknown in multiple authored documents. Ordinarily this
would result in incorrect references.

To prevent such collisions \Lollipop\ can use local
references: the command \refcs{LocalReferences} has default \n{no},
and specifying 
\Ver>LocalReferences:yes<Rev
creates local \file{aux} files for each input file.

\Section[sec:bib] Bibliography citations

\Lollipop\ has as yet no separate facilities for bibliographies such
as an interface to Bib\TeX. However, since a bibliography is just a
list, referencing items in it is quite easy.

\Example
\DefineList:BibList item:left [ itemCounter ] item:stop
 label:start [ itemCounter ] label:stop Stop
In this example we shall have occasion to refer to 
\ref[Abee80] and~\ref[Ceede79].\par
\Indent:no Bibliography
\BibList \item[Ace55] C.D. Ace, Inscrutible title.
\item[Abee80] E.F. Abee, Worthless drivel.
\item[Ceede79] G.H. Ceede, Contractual obligation.
\>
\ExampleStop

Here is a way to customize the label (if you need to refresh your
memory about description lists, see
section~\ref[sec:description:list]).

\Example
\DefineList:BibList item:left [ itemCounter ] item:stop
 label:start ( description ) label:stop Stop
In this example we shall have occasion to refer to 
\ref[Abe80] and~\ref[Ceedee79].\par
\Indent:no Bibliography
\BibList \item[Aace55] Aace55
C.D. Aace, Inscrutible title.
\item[Abe80] Abe80
E.F. Abe, Worthless drivel.
\item[Ceedee79] Ceedee79
G.H. Ceedee, Contractual obligation.
\>
\ExampleStop

\Chapter[chap:external-files] External Files

Some document require information to be collected during a run. Such
information typically is a table of contents or index, and it is
gathered in an external file. (The reason for gathering such
information in a file at all is that often some external manipulation,
for instance sorting of an index, is needed.) Since there are many
possibilities for external files (mathematical monographs may have a
list of definitions, or a list of notations) \Lollipop\ does not
predefine such files, but supplies all of the tools for creating them.

External files involve four actions: 
\Enumerate\item The file should be declared.
\item It should be specified what information is to be written to the
file.
\item The formatting of the contents of the file has to be specified.
\item The file has to be loaded.
\>

\Section Declaring and loading an external file

The first act, declaring the existence of the external file is very
easy with the command \refcs{DefineExternalFile}:
 an internal name and a three-character file name extension have
to be given as parameters.
\Ver>\DefineExternalFile:contents=toc<Rev
With this definition, if the document is called \file{book.tex} then
the `contents' will be gathered in a file called \file{book.toc}.

For each external file \n{Foo} there is a command to determine whether
that file will be regenerated in the next run of \TeX:
\refcs{WriteFoo} with values \n{yes}/\n{no} will allow or prevent the
file being regenerated. The value \opt{yes} is default. The
command \refcs{WriteExtern} (values \n{yes}/\n{no})
can be used to prevent writing out any external files (including the
\file{.aux} file that keeps track of references).

The final act, loading an external file, is as easy as declaring it:
use \refcs{LoadExternalFile} as in
\Ver>\LoadExternalFile:contents<Rev
This does not cause any page breaks or headings to be set over the
loaded material, so you have to do that explicitly.

\Section[sec:ext-option] Generating external files

Next, macros that write to the table of contents have to declare this
information. The \refopt{external} option is used for this.
Any counter that the construct has will be written out
automatically, and the style designer usually has to specify only
that the title will be written out.
\Ver>\DefineHeading:Section
    [...]
    external:contents title external:stop<Rev

There is no objection to a construct writing information to more than
one external file.

\Section[sec:ext-item] Formatting an external file

The hardest part is declaring the formatting of an external file. For
this a separate generic construct exists: the `external item' with
defining command \refcs{DefineExternalItem}. For example, if
\cs{Section} writes to \n{contents}, than an external item \n{Section}
corresponding to this file has to be declared. The option
\refopt{file} is use to declare to which file the external item
belongs. This way the same name can be reused for more than one file.

\Ver>\DefineExternalItem:Section file:contents
    [...] Stop<Rev

An external item is basically a list with just one item. Thus, the
option \refopt{item} is available. The elements of an external item are
the label (the counter value), the page number where the information
was generated, and the title. 
For the label (say for a construct \cs{Foo})
an option \refopt{FooLabel} is created.
Thus the typical formating looks like
\Ver>\DefineExternalItem:Chapter file:contents
    item:left ChapterLabel item:stop
    title begingroup Spaces:2 Style:italic Page endgroup
    Stop<Rev
In fact, a control sequence \refcs{FooLabel} is created, which
can be used in other external items.

Since an external item is a list in itself, you have to pull a
certain trick to get items for subsections to indent further than
those for sections. This is what the command \cs{PushIndentLevel} was
designed for.

A typical indented item looks like:
\Ver>\DefineExternalItem:SubSection file:contents
    PushIndentLevel PushIndentLevel
    item:left SectionLabel . SubSectionLabel item:stop
    title begingroup Spaces:2 Style:italic Page endgroup
    Stop<Rev

\Section Example

The following example is for a typical table of contents that
records sections and subsections. In good old-fashioned style, the
subsections are indented with respect to the sections.

\Example
\DefineExternalFile:TheContents=tct
\DefineHeading:TestChapter Style:bold
 line:start TestChapterCounter Spaces:2 title line:stop
 external:TheContents title external:stop Stop
\DefineExternalItem:TestChapter file:TheContents
 item:left Style:bold TestChapterLabel item:stop title white:5pt
      Page par Stop
\DefineHeading:TestSection Style:italic
 line:start TestChapterCounter . TestSectionCounter 
            Spaces:2 title line:stop
 external:TheContents title external:stop Stop
\GoverningCounter:TestSection=TestChapter
\DefineExternalItem:TestSection file:TheContents PushIndentLevel
 item:left Style:bold TestChapterLabel . TestSectionLabel item:stop 
 title white:5pt Page par Stop

\LoadExternalFile:TheContents
\TestChapter First heading\par
\TestSection First subheading\par
Some text might be nice.
\TestSection Second subheading\par
Some more text.
\TestChapter Second heading\par
\TestSection Third subheading\par
Yet more text.
\TestSection Fourth subheading\par
And again: text.
\ExampleStop